═══ 1. Calendar (ExCal) ═══ The calendar provides a means for a user to keep track of their day-to-day activities. The calendar allows you to view months at a glance and to schedule events for one or more days. The events may be scheduled to occur on a single day, daily, monthly, weekly, or yearly. To remind you of a given event, you can set an event alarm. The ExCal package also includes a simple address book. Related information: o Getting started o Example use of calendar and events o Calendar views o Calendar events o Calendar and CUA user interfaces ═══ 1.1. Calendar and CUA User Interfaces ═══ The Calendar is an example which demonstrates some of the key features of Workplace interface and the value of using IBM's Common User Access (CUA) methodology for user interface design and behavior. ═══ 1.2. Getting Started ═══ When you first install the calendar, a folder is created which contains a calendar, a folder of event templates, a folder of default places, and an address book. When opened, the calendar displays one or more events. When you double-click on the calendar, it is displays in its default view, the Glance view. The Event Templates folder contains a set of template events (Lunch, Meeting, Vacation, etc.). You can add additional event templates if needed. You can create new events from these templates by dragging one to the calendar. You can also create new events by selecting one of the the event template names listed in the Create event menu choice of a calendar or event. The Places folder contains a set of default places which can be used when scheduling where events occur. You can add additional places if needed. The Address Book help you keep track of your friends. To create a new person for the address book, select Create person from the address book pop-up menu. To get started, double click the calendar. This will open the calendar in its default glance view. You can then add events. ═══ 1.3. Example use of Calendar and Events ═══ Joseph is working at his desk when he receives a phone call from an important client. This client would like to meet with Joseph on a particular day to review his latest sales proposal. Joseph decides to consult his online calendar to determine if the meeting will be possible. Joseph will need to glance at his calendar and see what, if anything, is already scheduled for that day. Joseph double clicks the calendar icon on his screen to open his calendar. Upon double clicking Joseph is presented with a window showing the calendar in its default glance view. The leftmost pane shows the current month in a grid-like fashion similar to what a user would expect to see in a traditional calendar. Each day of the month is shown in a cell of the grid. Just as Joseph may write in events for a given day of the month on a traditional calendar, Joseph may choose one or more of the days in the glance view to show or change the events for. Joseph double clicks on the proposed day to determine what events he has already scheduled for that day. The events for each day are displayed in the rightmost pane of the glance view. Upon viewing the events Joseph sees that he has two morning events for that day and none in the afternoon. He would like to schedule the meeting for two in the afternoon. He confirms this time with his client and schedules a meeting in his office. He does this by moving the cursor to the proposed day and bringing up the pop-up menu for this day. He then chooses "Create event" which creates the event for this day. The event is created with a default time and place, which he modifies as described below. Changing event time Joseph is still working at his desk an hour later when his important client calls back. The client informs Joseph that due to a conflict he would like to make their meeting two hours later. Since Joseph has already scheduled the meeting in his calendar, he must now change the time of the scheduled event. Joseph goes to his computer and opens his calendar in the glance view. He opens on the proposed day to see the events for this day. Joseph moves the cursor over the meeting event and brings up its pop-up menu. From this pop-up he chooses "Start time". A cascaded menu then appears with times in half hour increments. He selects 4pm and the start time is changed for his event. He repeats these steps in order to set "End time" for the event. Joseph is curious and decides he would like to explore a different way to change his event's time. He opens his event which displays the settings view for his event. The settings notebook has size pages (i.e. Summary, Time, Place, Attachments, Window, and General). He selects the time page. From this page he sees two spin boxes which display the event's "Start time" and "End time". He then changes the event's time with these. Having accomplished that task, Joseph becomes more curious and wants to explore the use of direct manipulation to change the place of his event. Joseph will need an overhead projector to show his clients some business information. He will therefore need to move his customer meeting to a classroom which has this equipment. He clicks on another day of the month and notices that there is an event which has the same place he would like to have for his customer meeting. He opens the setting for the event and notices that it has a "well" with a place icon in it. Joseph starts dragging the place over his event and drops it. The place is updated to reflect the same place as the other event had. The time of day could be changed in a similar fashion using the time "well" in the event. The time and place well also have a pop-up menu that can be used to change the place or time of the event. Associating objects with an event Joseph is reviewing his materials for his scheduled meeting with his important client. He remembers that he has some items (i.e. legal documents and signature forms) which he must remember to bring to the meeting. He would like to attach the list of these items to his scheduled event in the calendar so that he does not forget them. Joseph goes to his screen to find the necessary documents and forms. He drags the items over to his event and drops them. They are then added to his event's list of attachments. He wants to make sure that he has everything, so he opens his event to double check. Upon viewing the attachments, he sees that he is missing a signature form. He finds the form and drags it over to the attachments list in his open event. Joseph could add the forms to the "Attachments Open on Alarm" list (not shown above) instead of the "Attachments List" on the same page if he wanted them to be opened at the time the event alarm occurred just as if he had double-clicked them. After finishing all this, Joseph gets another call from his client saying that he would like to change the day of their meeting. He would like to move it forward a couple of days. Joseph opens his calendar in the glance view and finds the meeting event on the previously scheduled day. He drags the event over the new proposed day and drops it. The event is then updated to occur on the new day. Calendar and event presentation cues to purpose While preparing for his meeting, Joseph glances at his calendar and notices that the day before his meeting is a weekend. This weekend will affect his ability to obtain the proper financial documents from his bank. Realizing this fact, he changes his plans for the Friday before the weekend in order to get the documents before his meeting. Joseph was able to determine this quickly because the weekends are distinguished from the weekdays using different shadings. He then plans to have the documents completed the prior Friday for his Monday meeting. While sitting at his desk, Joseph receives a call from a friend wanting to make dinner plans for that evening. Joseph again consults his calendar and easily finds the current day as it has a different shading then the other days. He views his events for this day and sees that he is free for dinner. Joseph then brings up the pop-up menu for this day to create a new event. He is reassured that he is adding the event to the correct day because the day has context emphasis (i.e. dashed box). After finishing the phone call with his friend, Joseph's manager informs him that there is a mandatory two day seminar which he must attend. Joseph opens his calendar and selects the two days. The two days are hilighted indicating that they have been selected. He then brings up a pop-up menu for the two days and schedules and creates a seminar event for them. Later that day, Joseph sits back and looks at his calendar. He realizes that this is going to be a busy month. He notices that he has something scheduled for most days because the number for each day is underlined indicating that he has event(s) scheduled for those days. The calendar provides visual feedback to tell the user what action is taking place or what object is being acted on. Additionally the calendar combines different colors and emphasis to indicate to the user unique things about certain days. (i.e. diagonal lines). ═══ 1.4. Calendar Events ═══ Related information: o Viewing calendar events o Setting event alarms o Adding and removing event attachments o Changing event time or date ═══ 1.5. Calendar Views ═══ The calendar supports three views of its events: Glance, Icon, and Details view. o Calendar Glance view o Calendar Icon view o Calendar Details view The font and color of each of these can be set using the Font, Color, or Scheme Palette in your System Setup folder. ═══ 1.6. Calendar Glance View ═══ The calendar's default view is Glance view. This is similar to the "month at a glance" presentation found in most traditional calendars. The leftmost pane, glance, shows the current month in a grid-like fashion. From here you have various menu choices depending upon whether the pop-up menu is initiated on the day or the entire pane. If you bring up a pop-up menu from the day the menu choices are as follows o View events o Delete events o Create events If you bring up a pop-up menu for the left pane, the menu choices are as follows o Next month o Previous month o Month o Other month o Refresh now o Sort events The rightmost pane, events, shows all the events which occur on a given day or days. If you bring up a pop-up menu over an event the following menu for the event will appear. The pop-up menu includes o Start time o Duration in hours o End time o Day o Repeat o Replace place with o Turn alarm on If you bring up the pop-up menu for the rightmost pane the pop-up menu includes o Create event o Delete past events ═══ 1.7. Calendar Icon View ═══ The icon view of the calendar displays all the events in the calendar with no filtering based on days or months as provided by the glance view. ═══ 1.8. Calendar Details View ═══ The details view of the calendar displays all the events in the calendar in a report-like format. Each event is listed with its summary information (i.e. date, time, and place). ═══ 1.9. Viewing Calendar Events ═══ You can view the events for a single or multiple days from the calendar. There are several methods provided for viewing the events, depending upon your preference. Glance day pop-up menu This is done by selecting mouse button 2 while the cursor is over the day to viewed. If you would like to see the events occurring for more than one day, select the days and then select the "View Events" choice. This will cause the appropriate events to be displayed in the right pane of the calendar window. Any events previously in view will remain in view. Double click on glance day You can double-click the mouse over the day and only the events for that day will be displayed in the right pane of the calendar. Calendar menu "Selected" choice This method is similar to the pop-up menu method except that you select "View Events" from the "Selected" menu pulldown. The calendar events are displayed on the right pane of the calendar window as shown below. ═══ 1.10. View Events ═══ This option displays all the events occurring on the specified day(s). If the pop-up menu is for a day which is not selected, only the events for that day are displayed. If the pop-up menu is for a day which is selected, the events occurring on that day and any other selected days are displayed. For additional information on viewing calendar events, refer to Viewing Calendar Events ═══ 1.11. Create Events ═══ This option creates an event(s) for the specified day(s). If the pop-up menu is for a day which is not selected, an event is created for that day only. If the pop-up menu is for a day which is selected, a separate event is created for that day and each selected day. If the pop-up menu is on the events pane, an event is created for the first day in view (or, if no days are in view, an event is create for today). ═══ 1.12. Delete Events ═══ This option deletes all events occurring on the specified day(s). If the pop-up menu is for a day which is not selected, only the events for that day are deleted. If the pop-up menu is for a day which is selected, the events occurring on that day and any other selected days are deleted. ═══ 1.13. Next Month ═══ This displays the next month of the calendar. ═══ 1.14. Previous Month ═══ This displays the previous month of the calendar. ═══ 1.15. Month ═══ You can use this option to quickly change the glance view month to a month which occurs within seven months of the current month. ═══ 1.16. Other Month ═══ This option brings up a dialog allowing you to select which month is displayed by the calendar. ═══ 1.17. Refresh Now ═══ This option refreshes both panes of the glance view. ═══ 1.18. Sort Events ═══ Choose this option to sort the events by name or time. ═══ 1.19. Import/Export from PMDiary ═══ Choose this option to import from or export to a PMDiary daily planner file (*.$D$). The Calendar will try to match events it is importing from PMDiary by title and time. When exporting Calendar will merge the events it contains with the PMDiary entries in the export file. ═══ 1.20. Delete Past Events ═══ This choice presents a list of events which occurred before the current date. Pick from the list of events those you no longer want and select Delete. ═══ 1.21. Programming API ═══ The Calendar supports Workplace Shell setup strings. These strings can be passed to a Calendar to create events with the SysSetObjectData or WinSetObjectData API. The Calendar will create an event and pass it the setup string. Generally this is done as part of a customized Calendar installation. Note: You can create events directly using the SysCreateObject or WinCreateObject API and specifying the event class ExEvent. In this case, the CREATEEVENT keyword is not necessary (i.e., the CREATEEVENT keyword is only used by Calendar instances). See EXCAL.CMD included in this package for more details. CREATEEVENT= New event title. DATE= Date for the new event, MM/DD/YY. Defaults to current date. STARTTIME= Start of event, HH:MM, in 24 hour format. Defaults to noon or current hour, whichever is later. ENDTIME= End of event, HH:MM, in 24 hour format. Defaults to 13:00 or current hour plus one hour, whichever is later. REPEAT= Valid values are NONE, WEEKLY, MONTHLY, or ANNUALLY. ALARM= Valid values are ON or OFF. PERSONAL= Valid values are YES or NO. If YES, the event will not be included in exports to PMDiary. PLACE= The title of an existing place. NOTES= Notes for the event. ATTACHMENTWPOBJECTHANDLES= The list of object handles attached to the event, separated by spaces. The attachments must exist in the same folder (calendar) as the event. ATTACHMENTWPOBJECTIDS= Same as ATTACHMENTWPOBJECTHANDLES except it accepts object IDs (e.g., for the Templates folder, see \OS2\INI.RC for the standard system object IDs). ALARMATTACHMENTWPOBJECTHANDLES= The list of object handle attached to the event, separated by spaces, which will be opened when the event alarm occurs. The attachments must exist in the same folder (calendar) as the event. ALARMATTACHMENTWPOBJECTIDS= Same as ALARMATTACHMENTWPOBJECTHANDLES except it accepts object IDs (e.g., for the OS/2 System folder, see \OS2\INI.RC for the standard system object IDs). OPENONALARM= Valid values are YES or NO. If YES, the event will be opened when the event alarm occurs. BEEPONALARM= Valid values are YES or NO. If YES, the event will beep when the event alarm occurs. EXPORTTOPMDIARY= Specifies a PMDiary file to export calendar events. The file name must be fully qualified. The events starting from the current time to two years into the future are exported. During exporting, existing PMDiary events are merged with the ExCal events. IMPORTFROMPMDIARY= Specifies a PMDiary file to import calendar events. The file name must be fully qualified. The setup string below would create an annual event. CREATEEVENT=Happy New Years!; DATE=01/01/93; REPEAT=ANNUALLY; STARTTIME=00:01; ALARM=ON This setup string can be passed to the Calendar using the WinSetObjectData API, the REXX SysSetObjectData, or the Workplace Shell wpSetup method. The Calendar creates an Event and passes it the entire setup string passed to the Calendar including the CREATEEVENT keyword (which is ignored by the newly created event). Note: Only one event can be created per setup invocation because the CREATEEVENT keyword can only be specified once in the setup string. Similarly, places can be created by the Calendar. Note: You can create places directly using the SysCreateObject or WinCreateObject API and specifying the place class ExPlace. In this case, the CREATEPLACE keyword is not necessary (i.e., the CREATEPLACE and PLACEFOLDER keywords are only used by Calendar instances). Only one place can be created per setup invocation because the CREATEPLACE keyword can only be specified once in the setup string. CREATEPLACE= New place title. PLACEFOLDER= Object ID or fully qualified path of folder where new place is to be created. Default is . ADDRESS= Address. PHONE= Phone number. CITY= City. STATE= State. ZIPCODE= Zip code. CONTACTNAME= Contact name. CONTACTPHONE= Contact phone number. CAPACITY= Number of people the place can confortably hold. NOTES= Notes about the place. The Calendar, Event, and Place objects also support the following keywords. QUERYSETUPSTRINGSLENGTH= Returns the length of the setup strings necessary to recreate the ExCal object into into a named shared memory object. QUERYSETUPSTRINGS= Returns the setup strings necessary to recreate the ExCal object into into a named shared memory object. WRITESETUPSTRINGSTOFILE= Requests that the event, place, or calendar write the setup strings necessary to recreate it to the named file. The file name must be fully qualified. If multiple setup strings are required, they are separated by a NULL character and the data is terminated by a double-NULL character (a "pszz"). Note the Calendar object writes out the setup strings necessary to recreate it, the Place objects, and the Event objects it contains. ═══ 2. Events (ExCal) ═══ An event provides a means for a user to keep track of their day-to-day activities. An event may be scheduled to occur on a single day, daily, monthly, weekly, or yearly. To remind you of a given event, you can set an event alarm. Related information: o Getting started o Example use of events o Changing event time or date o Setting event alarms o Adding and removing event attachments o Calendar and CUA user interfaces ═══ 2.1. Setting Event Alarms ═══ You can set an alarm for each event in the calendar. There are various ways that can be used to set the alarms, depending upon your preference. Event pop-up menu Display the event's pop-up menu by selecting mouse button 2 while the cursor is over the event whose alarm is to be set. If more there is more than one event whose alarm is being set, extended selection may be used to choose the events. The pop-up menu should then be brought up and the "Turn alarm on" or "Turn alarm off" choice selected. This menu item is toggled between "on" and "off" depending upon whether the event has an alarm set or not. The default is for the alarm to occur five minutes prior to the start time of the event. Open Event Settings Open the event's Settings by double-clicking mouse button 1 while the cursor is over the event whose alarm is to be set. Once open, the events setting's Summary page is displayed. From here you can toggle the alarm on or off. Additionally, you can change the time the alarm is to go off, relative to the start of the event. Calendar menu "Selected" choice This method is similar to the pop-up menu method except that you select "Turn alarm on" from the "Selected" menu pulldown. ═══ 2.2. Changing Event Time or Date ═══ There are various ways to change an events time and/or date. Event pop-up menu Move the cursor over the event and bring up its pop-up menu. The pop-up menu includes o Start time o Duration in hours o End time o Day o Repeat Event Settings Open the event settings and turn to the Time page. The Time page contains spin boxes which can be used to change the date (month, day, and year) and the start and end time. Direct Manipulation Each event contains a time "well" which will always contain only one time object. Using direct manipulation, you can drag any time object to the time "well" and it replace the one currently there. The time well also has a pop-up menu that can be used to change the time of the event. ═══ 2.3. Start time ═══ Use this choice to set the starting time of an event. Once set the ending time is adjusted based on the duration of the event. If additional granularity is need for time (e.g. 8:15), open the Settings for the event and turn to the Time page. ═══ 2.4. Duration ═══ Use this choice to set the duration of an event. Upon changing the duration of an event, the starting time for the event remains the same, and the ending time is adjusted to account for the change in duration. If a longer duration is needed (e.g. 6 hours), open the Settings for the event and turn to the Time page. ═══ 2.5. End time ═══ Use this choice to set the ending time of an event. Upon changing the ending time of an event, the duration of the event is changed to account for the change in the ending time. There is no changes made to the starting time. If additional granularity is need for time (e.g. 8:15), open the Settings for the event and turn to the Time page. ═══ 2.6. Day ═══ Use this choice to set the day of the event. The cascaded menu choices are the current day (today) and the next six days. If the event day you want to set is more than six days from today, open the event Settings and turn to the Time page to set the event date. ═══ 2.7. Repeat ═══ Choose one of these choices to have an event repeat for a given number of days, weeks, months, or years. You can limit the number of occurrences of a repeating events by selecting one of the menu cascade choices (e.g. "For two days"), or by opening the event Settings and turning to the Time page to set the number of occurrences. ═══ 2.8. Replace place with ═══ Choose one of these choices to change the location where an event is to occur. Not all of the available places are shown in this menu: Open the event Settings and turn to the Places page to see all available locations. Note: You may create more places by selecting Create another from an existing place. Also, you can set the place of an event by dropping a place on the event. ═══ 2.9. Turn alarm on ═══ This toggles the event alarm on or off. If the alarm is being turned on, it is set to occur five minutes prior to the event start time. This may be changed by opening the settings of the event and changing the alarm advance minutes from the Summary page. ═══ 2.10. Personal ═══ This toggles the personal attribute of an event. Personal events are excluded from exports to PMDiary. ═══ 2.11. Adding and Removing Event Attachments ═══ Attachments may be associate with an event as a reminder of things you might need when the event occurs. For example, you may have a business meeting to which you would like to bring presentation material. You can associate any workplace object with an event, such as a document, video presentation, or program. Each event can have any number of attachments associated with it. To do this, open the event settings and turn to the "Attachments" page. Using direct manipulation techniques, drag the object you would like to associate to the the attachment area of the event setting's page. Attachments added to the "Attachments Opened On Alarm" are opened when the event alarm occurs. This can be used to open a document or start a program when the event occurs. Attachments can be removed by either deleting the attachment, or moving the attachment to another folder. Note: Event attachments can only be shadows (references to) other objects such as documents and forms, or program references. The attachments are deleted when the event is deleted. ═══ 3. Places (ExCal) ═══ Places are used in conjuction with events. An event provides a means for a user to keep track of their day-to-day activities. An event may be scheduled to occur on a single day, daily, monthly, weekly, or yearly. To remind you of a given event, you can set an event alarm. Related information: o Getting started o Example use of events and places ═══ 3.1. Make default ═══ Use this choice to set the default place used by newly created events. When the Calendar is initially installed, the place named Favorite Place is the default place for newly created events. ═══ 4. Address Book and Persons (ExCal) ═══ The address book provides a means for a user to keep track of their friends. To create a new person for the address book, select Create person from the address book pop-up menu. Note: You can hide an unneeded column of detail information shown for each person by deselecting the column name in the Details to display list shown in the third View page of the Address Book's Settings view.